 /*******************************************************************************
  * Copyright (c) 2005, 2007 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  *******************************************************************************/
 package org.eclipse.ui.application;

 import org.eclipse.core.runtime.Assert;
 import org.eclipse.core.runtime.IStatus;
 import org.eclipse.core.runtime.Status;
 import org.eclipse.swt.widgets.Composite;
 import org.eclipse.swt.widgets.Control;
 import org.eclipse.swt.widgets.Shell;
 import org.eclipse.ui.IMemento;
 import org.eclipse.ui.IWorkbenchPreferenceConstants;
 import org.eclipse.ui.PlatformUI;
 import org.eclipse.ui.WorkbenchException;
 import org.eclipse.ui.actions.ActionFactory;
 import org.eclipse.ui.internal.WorkbenchWindowConfigurer;
 import org.eclipse.ui.internal.util.PrefUtil;
 import org.eclipse.ui.intro.IIntroManager;

 /**
  * Public base class for configuring a workbench window.
  * <p>
  * The workbench window advisor object is created in response to a workbench
  * window being created (one per window), and is used to configure the window.
  * </p>
  * <p>
  * An application should declare a subclass of <code>WorkbenchWindowAdvisor</code>
  * and override methods to configure workbench windows to suit the needs of the
  * particular application.
  * </p>
  * <p>
  * The following advisor methods are called at strategic points in the
  * workbench window's lifecycle (as with the workbench advisor, all occur
  * within the dynamic scope of the call to
  * {@link PlatformUI#createAndRunWorkbench PlatformUI.createAndRunWorkbench}):
  * <ul>
  * <li><code>preWindowOpen</code> - called as the window is being opened;
  * use to configure aspects of the window other than actions bars</li>
  * <li><code>postWindowRestore</code> - called after the window has been
  * recreated from a previously saved state; use to adjust the restored
  * window</li>
  * <li><code>postWindowCreate</code> - called after the window has been created,
  * either from an initial state or from a restored state; used to adjust the
  * window</li>
  * <li><code>openIntro</code> - called immediately before the window is opened in
  * order to create the introduction component, if any.</li>
  * <li><code>postWindowOpen</code> - called after the window has been
  * opened; use to hook window listeners, etc.</li>
  * <li><code>preWindowShellClose</code> - called when the window's shell
  * is closed by the user; use to pre-screen window closings</li>
  * </ul>
  * </p>
  *
  * @since 3.1
  */
 public class WorkbenchWindowAdvisor {

     private IWorkbenchWindowConfigurer windowConfigurer;

     /**
      * Creates a new workbench window advisor for configuring a workbench
      * window via the given workbench window configurer.
      *
      * @param configurer an object for configuring the workbench window
      */
     public WorkbenchWindowAdvisor(IWorkbenchWindowConfigurer configurer) {
         Assert.isNotNull(configurer);
         this.windowConfigurer = configurer;
     }

     /**
      * Returns the workbench window configurer.
      *
      * @return the workbench window configurer
      */
     protected IWorkbenchWindowConfigurer getWindowConfigurer() {
         return windowConfigurer;
     }
     
     /**
      * Performs arbitrary actions before the window is opened.
      * <p>
      * This method is called before the window's controls have been created.
      * Clients must not call this method directly (although super calls are okay).
      * The default implementation does nothing. Subclasses may override.
      * Typical clients will use the window configurer to tweak the
      * workbench window in an application-specific way; however, filling the
      * window's menu bar, tool bar, and status line must be done in
      * {@link ActionBarAdvisor#fillActionBars}, which is called immediately
      * after this method is called.
      * </p>
      */
     public void preWindowOpen() {
         // do nothing
 }

     /**
      * Creates a new action bar advisor to configure the action bars of the window
      * via the given action bar configurer.
      * The default implementation returns a new instance of {@link ActionBarAdvisor}.
      *
      * @param configurer the action bar configurer for the window
      * @return the action bar advisor for the window
      */
     public ActionBarAdvisor createActionBarAdvisor(IActionBarConfigurer configurer) {
         return new ActionBarAdvisor(configurer);
     }
     
     /**
      * Performs arbitrary actions after the window has been restored,
      * but before it is opened.
      * <p>
      * This method is called after a previously-saved window has been
      * recreated. This method is not called when a new window is created from
      * scratch. This method is never called when a workbench is started for the
      * very first time, or when workbench state is not saved or restored.
      * Clients must not call this method directly (although super calls are okay).
      * The default implementation does nothing. Subclasses may override.
      * It is okay to call <code>IWorkbench.close()</code> from this method.
      * </p>
      *
      * @exception WorkbenchException thrown if there are any errors to report
      * from post-restoration of the window
      */
     public void postWindowRestore() throws WorkbenchException {
         // do nothing
 }

     /**
      * Opens the introduction componenet.
      * <p>
      * Clients must not call this method directly (although super calls are okay).
      * The default implementation opens the intro in the first window provided
      * if the preference IWorkbenchPreferences.SHOW_INTRO is <code>true</code>. If
      * an intro is shown then this preference will be set to <code>false</code>.
      * Subsequently, and intro will be shown only if
      * <code>WorkbenchConfigurer.getSaveAndRestore()</code> returns
      * <code>true</code> and the introduction was visible on last shutdown.
      * Subclasses may override.
      * </p>
      */
     public void openIntro() {
         // TODO: Refactor this into an IIntroManager.openIntro(IWorkbenchWindow) call

         // introOpened flag needs to be global
 IWorkbenchConfigurer wbConfig = getWindowConfigurer().getWorkbenchConfigurer();
         final String key = "introOpened"; //$NON-NLS-1$
 Boolean introOpened = (Boolean ) wbConfig.getData(key);
         if (introOpened != null && introOpened.booleanValue()) {
             return;
         }

         wbConfig.setData(key, Boolean.TRUE);

         boolean showIntro = PrefUtil.getAPIPreferenceStore().getBoolean(
                 IWorkbenchPreferenceConstants.SHOW_INTRO);
         
         IIntroManager introManager = wbConfig.getWorkbench().getIntroManager();
         
         boolean hasIntro = introManager.hasIntro();
         boolean isNewIntroContentAvailable = introManager.isNewContentAvailable();
         
         if (hasIntro && (showIntro || isNewIntroContentAvailable)) {
             introManager
                     .showIntro(getWindowConfigurer().getWindow(), false);

             PrefUtil.getAPIPreferenceStore().setValue(
                     IWorkbenchPreferenceConstants.SHOW_INTRO, false);
             PrefUtil.saveAPIPrefs();
         }
     }

     /**
      * Performs arbitrary actions after the window has been created (possibly
      * after being restored), but has not yet been opened.
      * <p>
      * This method is called after the window has been created from scratch,
      * or when it has been restored from a previously-saved window. In the latter case,
      * this method is called after <code>postWindowRestore</code>.
      * Clients must not call this method directly (although super calls are okay).
      * The default implementation does nothing. Subclasses may override.
      * </p>
      */
     public void postWindowCreate() {
         // do nothing
 }

     /**
      * Performs arbitrary actions after the window has been opened (possibly
      * after being restored).
      * <p>
      * This method is called after the window has been opened. This method is
      * called after the window has been created from scratch, or when
      * it has been restored from a previously-saved window.
      * Clients must not call this method directly (although super calls are okay).
      * The default implementation does nothing. Subclasses may override.
      * </p>
      */
     public void postWindowOpen() {
         // do nothing
 }

     /**
      * Performs arbitrary actions as the window's shell is being closed
      * directly, and possibly veto the close.
      * <p>
      * This method is called from a ShellListener associated with the window,
      * for example when the user clicks the window's close button. It is not
      * called when the window is being closed for other reasons, such as if the
      * user exits the workbench via the {@link ActionFactory#QUIT} action.
      * Clients must not call this method directly (although super calls are
      * okay). If this method returns <code>false</code>, then the user's
      * request to close the shell is ignored. This gives the workbench advisor
      * an opportunity to query the user and/or veto the closing of a window
      * under some circumstances.
      * </p>
      *
      * @return <code>true</code> to allow the window to close, and
      * <code>false</code> to prevent the window from closing
      * @see org.eclipse.ui.IWorkbenchWindow#close
      * @see WorkbenchAdvisor#preShutdown()
      */
     public boolean preWindowShellClose() {
         // do nothing, but allow the close() to proceed
 return true;
     }

     /**
      * Performs arbitrary actions after the window is closed.
      * <p>
      * This method is called after the window's controls have been disposed.
      * Clients must not call this method directly (although super calls are
      * okay). The default implementation does nothing. Subclasses may override.
      * </p>
      */
     public void postWindowClose() {
         // do nothing
 }

     /**
      * Creates the contents of the window.
      * <p>
      * The default implementation adds a menu bar, a cool bar, a status line,
      * a perspective bar, and a fast view bar. The visibility of these controls
      * can be configured using the <code>setShow*</code> methods on
      * <code>IWorkbenchWindowConfigurer</code>.
      * </p>
      * <p>
      * Subclasses may override to define custom window contents and layout,
      * but must call <code>IWorkbenchWindowConfigurer.createPageComposite</code>.
      * </p>
      *
      * @param shell the window's shell
      * @see IWorkbenchWindowConfigurer#createMenuBar
      * @see IWorkbenchWindowConfigurer#createCoolBarControl
      * @see IWorkbenchWindowConfigurer#createStatusLineControl
      * @see IWorkbenchWindowConfigurer#createPageComposite
      */
     public void createWindowContents(Shell shell) {
         ((WorkbenchWindowConfigurer) getWindowConfigurer()).createDefaultContents(shell);
     }

     /**
      * Creates and returns the control to be shown when the window has no open pages.
      * If <code>null</code> is returned, the default window background is shown.
      * <p>
      * The default implementation returns <code>null</code>.
      * Subclasses may override.
      * </p>
      *
      * @param parent the parent composite
      * @return the control or <code>null</code>
      */
     public Control createEmptyWindowContents(Composite parent) {
         return null;
     }

     /**
      * Disposes any resources allocated by this window advisor.
      * This is the last method called on this window advisor by the workbench.
      * The default implementation does nothing.
      * Subclasses may extend.
      */
     public void dispose() {
         // do nothing.
 }
     
     /**
      * Saves arbitrary application specific state information.
      *
      * @param memento the storage area for object's state
      * @return a status object indicating whether the save was successful
      * @since 3.1
      */
     public IStatus saveState(IMemento memento) {
         // do nothing
 return Status.OK_STATUS;
     }
     
     /**
      * Restores arbitrary application specific state information.
      *
      * @param memento the storage area for object's state
      * @return a status object indicating whether the restore was successful
      * @since 3.1
      */
     public IStatus restoreState(IMemento memento) {
         // do nothing
 return Status.OK_STATUS;
     }
 }

